<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Chapter 18.  The Locking Subsystem</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="prev" href="program_faq.html" title="Programmer notes FAQ" />
    <link rel="next" href="lock_config.html" title="Configuring locking" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Chapter 18.  The Locking Subsystem </th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="program_faq.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="lock_config.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="lock"></a>Chapter 18.  The Locking Subsystem </h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <p>
          <b>Table of Contents</b>
        </p>
        <dl>
          <dt>
            <span class="sect1">
              <a href="lock.html#lock_intro">Introduction to the locking
        subsystem</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_config.html">Configuring locking</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_max.html">Configuring locking: sizing the
        system</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_stdmode.html">Standard lock modes</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_dead.html">Deadlock detection</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_timeout.html">Deadlock detection using
        timers</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_deaddbg.html">Deadlock debugging</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_page.html">Locking granularity</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_notxn.html">Locking without transactions</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_twopl.html">Locking with transactions: two-phase
        locking</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_cam_conv.html">Berkeley DB Concurrent Data Store locking conventions</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_am_conv.html">Berkeley DB Transactional Data
        Store locking conventions</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="lock_nondb.html">Locking and non-Berkeley DB
        applications</a>
            </span>
          </dt>
        </dl>
      </div>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="lock_intro"></a>Introduction to the locking
        subsystem</h2>
            </div>
          </div>
        </div>
        <p>
        The locking subsystem provides interprocess and intraprocess
        concurrency control mechanisms. Although the lock system is
        used extensively by the Berkeley DB access methods and
        transaction system, it may also be used as a standalone
        subsystem to provide concurrency control to any set of
        designated resources.
    </p>
        <p>
        The Lock subsystem is created, initialized, and opened by
        calls to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> with the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> or <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a>
        flags specified.
    </p>
        <p>
        The <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a> method is used to acquire and release locks.
        The <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a> method performs any number of lock operations
        atomically. It also provides the capability to release all
        locks held by a particular locker and release all the locks on
        a particular object. (Performing multiple lock operations
        atomically is useful in performing Btree traversals -- you
        want to acquire a lock on a child page and once acquired,
        immediately release the lock on its parent. This is
        traditionally referred to as
        <span class="emphasis"><em>lock-coupling</em></span>). Two additional
        methods, <a href="../api_reference/C/lockget.html" class="olink">DB_ENV-&gt;lock_get()</a> and <a href="../api_reference/C/lockput.html" class="olink">DB_ENV-&gt;lock_put()</a>, are provided. These methods
        are simpler front-ends to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a> functionality, where
        <a href="../api_reference/C/lockget.html" class="olink">DB_ENV-&gt;lock_get()</a> acquires a lock, and <a href="../api_reference/C/lockput.html" class="olink">DB_ENV-&gt;lock_put()</a> releases a lock that
        was acquired using <a href="../api_reference/C/lockget.html" class="olink">DB_ENV-&gt;lock_get()</a> or <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a>. All locks
        explicitly requested by an application should be released via
        calls to <a href="../api_reference/C/lockput.html" class="olink">DB_ENV-&gt;lock_put()</a> or <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a>. Using <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a> instead of
        separate calls to <a href="../api_reference/C/lockput.html" class="olink">DB_ENV-&gt;lock_put()</a> and <a href="../api_reference/C/lockget.html" class="olink">DB_ENV-&gt;lock_get()</a> also reduces the
        synchronization overhead between multiple threads or
        processes. The three methods are fully compatible, and may be
        used interchangeably.
    </p>
        <p>
        Applications must specify lockers and lock objects
        appropriately. When used with the Berkeley DB access methods,
        lockers and objects are handled completely internally, but an
        application using the lock manager directly must either use
        the same conventions as the access methods or define its own
        convention to which it adheres. If an application is using the
        access methods with locking at the same time that it is
        calling the lock manager directly, the application must follow
        a convention that is compatible with the access methods' use
        of the locking subsystem. See <a class="xref" href="lock_am_conv.html" title="Berkeley DB Transactional Data Store locking conventions">Berkeley DB Transactional Data
        Store locking conventions</a> for more
        information.
    </p>
        <p>
        The <a href="../api_reference/C/lockid.html" class="olink">DB_ENV-&gt;lock_id()</a> function returns a unique ID that may safely be
        used as the locker parameter to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV-&gt;lock_vec()</a> method. The
        access methods use <a href="../api_reference/C/lockid.html" class="olink">DB_ENV-&gt;lock_id()</a> to generate unique lockers for the
        cursors associated with a database.
    </p>
        <p>
        The <a href="../api_reference/C/lockdetect.html" class="olink">DB_ENV-&gt;lock_detect()</a> function provides the programmatic
        interface to the Berkeley DB deadlock detector. Whenever two
        threads of control issue lock requests concurrently, the
        possibility for deadlock arises. A deadlock occurs when two or
        more threads of control are blocked, waiting for actions that
        another one of the blocked threads must take. For example,
        assume that threads A and B have each obtained read locks on
        object X. Now suppose that both threads want to obtain write
        locks on object X. Neither thread can be granted its write
        lock (because of the other thread's read lock). Both threads
        block and will never unblock because the event for which they
        are waiting can never happen.
    </p>
        <p>
        The deadlock detector examines all the locks held in the
        environment, and identifies situations where no thread can
        make forward progress. It then selects one of the participants
        in the deadlock (according to the argument that was specified
        to <a href="../api_reference/C/envset_lk_detect.html" class="olink">DB_ENV-&gt;set_lk_detect()</a>), and forces it to return the value
        <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>,
        which indicates that a deadlock occurred. The thread receiving such an 
        error must release all of its locks and undo any incomplete modifications to the
        locked resource. Locks are typically released, and
        modifications undone, by closing any cursors involved in the
        operation and aborting any transaction enclosing the
        operation. The operation may optionally be retried.
    </p>
        <p>
        The <a href="../api_reference/C/lockstat.html" class="olink">DB_ENV-&gt;lock_stat()</a> function returns information about the status
        of the lock subsystem. It is the programmatic interface used
        by the <a href="../api_reference/C/db_stat.html" class="olink">db_stat</a> utility.
    </p>
        <p>
        The locking subsystem is closed by the call to
        <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a>.
    </p>
        <p>
        Finally, the entire locking subsystem may be discarded using
        the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> method.
    </p>
        <p>
        For more information on the locking subsystem methods, see
        the <a href="../api_reference/C/lock.html#locklist" class="olink">Locking
        Subsystem and Related Methods</a> section in the
        <em class="citetitle">Berkeley DB C API Reference Guide.</em>
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="program_faq.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="lock_config.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Programmer notes FAQ </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Configuring locking</td>
        </tr>
      </table>
    </div>
  </body>
</html>
